Django管理文档生成器

    在某种程度上，你可以使用admindocs来快为你自己的代码生成文档。这个应用的功能十分有限，然而它主要用于文档模板、模板标签和过滤器。例如，需要参数的模型方法在文档中会有意地忽略，因为它们不能从模板中调用。这个应用仍旧有用，因为它并不需要你编写任何额外的文档（除了docstrings），并且在 Django admin中使用很方便。

    要启用admindocs，你需要执行以下步骤：

    • 向 INSTALLED_APPS添加django.contrib.admindocs。
    • 向你的urlpatterns添加(r'^admin/doc/', include('django.contrib.admindocs.urls'))。 确保它在r'^admin/' 这一项 之前包含，以便/admin/doc/的请求不会被后面的项目处理。
    • 安装docutils Python 模块 (http://docutils.sf.net/)。

    一旦完成这些步骤，你可以开始通过你的admin接口和点击在页面右上方的“Documentation”链接来浏览文档。

    文档助手

    下列特定的标记可以用于你的，来轻易创建到其他组件的超链接：

    admindocs页面的models部分描述了系统中每个模型，以及所有可用的字段和方法（不带任何参数）。虽然模型的属性没有任何参数，但他们没有列出。和其它模型的关联以超链接形式出现。描述由字段上的help_text属性，或者从模型方法的docstrings导出。

    带有有用文档的模型看起来像是这样：

    视图参考

    • 视图所做工作的一个简短的描述。
    • 上下文，或者是视图的模板中可用变量的列表。
    • 用于当前视图的模板的名称。

    例如：

    1. from django.shortcuts import render
    3. from myapp.models import MyModel
    5. def my_view(request, slug):
    6.     """
    7.     Display an individual :model:`myapp.MyModel`.
    8.     **Context**
    10.     ``mymodel``
    11.         An instance of :model:`myapp.MyModel`.
    15.     :template:`myapp/my_template.html`
    17.     """
    18.     return render(request, 'myapp/my_template.html', context)

    admindocs的tags 和filters部分描述了Django自带的所有标签和过滤器（事实上，内建的标签参考 和 内建的过滤器参考文档直接来自于那些页面）。你创建的，或者由三方应用添加的任何标签或者过滤器，也会在这一部分中展示。

    模板参考

    虽然admindocs 并不包含一个地方来保存模板，但如果你在结果页面中使用`path/to/template.html`语法，会使用Django的模板加载器来验证该模板的路径。这是一个非常便捷的方法，来检查是否存在特定的模板，以及展示模板在文件系统的何处存放。

    admindocs页面上有一些很有用的书签：

    Documentation for this page

    Jumps you from any page to the documentation for the view that generates that page.

    Shows the content-type and unique ID for pages that represent a single object.

    Edit this object

    Jumps to the admin page for pages that represent a single object.

    为使用这些书签，你需要用带有is_staff 设置为 True的User登录Django admin，或者安装了XViewMiddleware并且你通过 中的IP地址访问站点。